﻿using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace NPipeline
{
    /// <summary>
    /// A IStage represents a set of tasks that can be performed on objects in a
    /// Queue, and methods used to communicate with other Stages in a <see cref="IPipeline"/>
    /// </summary>
    public interface IStage
    {
        /// <summary>
        /// Initialization takes place when the stage is added to a pipeline.
        /// Implementation of this method any neccessary setup that is required 
        /// for the driver to be able to correctly run the stage.
        /// <remarks>NOTE: Since this method is run when the stage is
        /// added to the pipeline, certain information, such as the downstream
        /// feeder for the stage may not yet be available until the pipeline is
        /// fully constructed.</remarks>
        /// </summary>
        /// <param name="context"></param>
        void Init(IStageContext context);

        // throws StageException
        /// <summary>
        /// Implementations of this method should perform any neccessary
        /// setup that needs to be done before any data is processes
        /// 
        /// Preprocessing is performed after initialization
        /// </summary>
        void PreProcess();

        /// <summary>
        /// Implementation of this method should atomically process a
        /// single data object and transfer any feed objects resulting from
        /// this processing to the downstream <seealso cref="IFeeder"/>.
        /// This Feeder can be obtained from the stage context made available
        /// during <see cref="Init"/>
        /// throws StageException
        /// </summary>
        /// <param name="obj"></param>
        void Process(object obj);

        /// <summary>
        /// Implementations of this method should do any additional 
        /// processing finalization after all data objects have been
        /// processed by the stage
        /// throws StageException
        /// </summary>
        void PostProcess();

        /// <summary>
        /// Implementations of this method should clean up any
        /// lingering resources that might otherwise be left allocated 
        /// if an exception is thrown during processing
        /// </summary>
        void Release();

    }
}
